LSD Docs/LSD Docs.iso/FILEZ/lsdspr06.dms/lsdspr06.adf/UltraCard.doc.pp/UltraCard.doc

Text File | 1990-09-07 | 105KB | 4,066 lines

                              UltraCard

                          Table of Contents

Introduction........................................................... 1
What is UltraCard?..................................................... 1
What Can UltraCard do?................................................. 2
When should I choose UltraCard?........................................ 4
Summary of UltraCard Specifications?................................... 5
Getting Started........................................................ 7
Copying your distribution disk......................................... 7
Configuring UltraCard on Floppy Disks.................................. 8
Configuring UltraCard on Hard Disks.................................... 8
Loading UltraCard..................................................... 10
Leaving UltraCard..................................................... 11
The ControlRoom Stack................................................. 12
The Starting point and the Return..................................... 12
Loading Other Stacks.................................................. 14
Setting the Pathways.................................................. 14
More.................................................................. 15
UltraCard Operating Basics............................................ 15
Browsing.............................................................. 18
Selecting Objects with the mouse...................................... 18
Changing Frames....................................................... 19
Using the GO Menu..................................................... 19
Using the Arrow Keys.................................................. 20
Going BACK............................................................ 20
Using the Recent Frame Selector....................................... 21
Accessing the Intuitive technologies BBS.............................. 22
Distribution of the Browser........................................... 23
UltraCard Language Specification...................................... 24
Introduction.......................................................... 24
General Syntax Rules.................................................. 24
Data Values........................................................... 25
Objects, Frames, Backdrops & Stacks................................... 25
Messages.............................................................. 28
Message Hierarchy..................................................... 29
Message Transformation................................................ 30
Message Handlers...................................................... 31
Variables -- Local & Global........................................... 32

                i

Statement Handlers.................................................... 33
Function Handlers..................................................... 34
Ultra Talk Expressions................................................ 35
OPERATORS............................................................. 35
UltraCard Statements.................................................. 37
UltraCard Functions.................................................. 116
UltraCard Global Variables........................................... 144
UltraCard Object Properties.......................................... 156
UltraCard Messages................................................... 162
Creating A New Stack................................................. 166
UltraCard Menu Reference............................................. 168
Index................................................................ 183

                ii

                           Introduction

Thank you for purchasing a license for UltraCard.  We at Intuitive
Technologies are proud to bring you this innovative software for your
Amiga.

UltraCard frees your creativity and allows you to create, for the first
time, quality applications for your Amiga without devoting your life to the
study of the Amiga's internal software.

We know that you will find UltraCard an enjoyable and exciting product and
hope that it will bring you hours of productive and creative pleasure.

                         What Is UltraCard?

UltraCard is, technically speaking, a multi-tasking hypermedia information
construction set.

UltraCard allows you to build a collection of information which is called a
STACK.  In the stack are elements called FRAMES that contain information.
The information contained in a frame may be graphic, audio, and textural.
The graphic information can be

                1

constructed of drawing objects and bitmaps.  The textural information can
be single line, multi-line and include hypertext links which allows action
to be taken based upon the contents of the textural data.

Using these stacks of frames you can construct information.  The
information can be static, such as a multi-level map of the United States
or active such as a name and address database, a top 10 music sampler or
even a user interface for sophisticated hardware.  Almost anything that the
Amiga can do, you can do with UltraCard, without years of study!

While the previous paragraphs describe what UltraCard is they still don't
tell you what you can do with UltraCard.

                   What can UltraCard do?

UltraCard can be used to create many things from databases, sophisticated
multi-media information retrieval systems, to educational material and
personal information systems such as appointment calendars and project
management outliners.

Some of the things we have constructed from UltraCard are:

1. A Names & Addresses stack for the UltraCard users.

                2

2. Multiple choice quizes with scoring for students.

3. The UltraCard Manual, Tutorial and Help stacks.

4. A Help stack for the MaxiPlan-III spreadsheet.

5. A music sampler for the top 10 hits of the week.

                3

                    When should I choose UltraCard?

UltraCard is good for use when you have a simple user-interface task and a
wide variety of information to communicate.  You can construct applications
that contain the full variety of Amiga facilities such as windows, menus,
sound and graphics.  Using the UltraCard Plus' external library facility
you can even add features to UltraTalk that expand its capabilities.  If
you have purchased UltraCard you may upgrade to UltraCard Plus by
contacting Intuitive Technologies at [phone].

                4

                  Summary of UltraCard Specifications:

* Support Amiga screen configurations:

320 or 640 pixel wide screen (supports MoreRows & PAL also)

200 or 400 pixel high screen (supports MoreRows & PAL also)

Overscan 704 or 354 by 240 or 480

2, 4, 8, 16, 32 or 64 (half-brite) colors

* Object oriented drawing tools including bitmap objects

Bitmap objects can be layered for sophisticated effects.

* Text, IFF and object oriented printing capability.

* UltraTalk scripting language for associating actions with objects.

Full featured language including built-in and user written functions and
external library support.

* Find and Sort facilities for "database" stacks.

                5

* Built-in Hypertext that associates action with words or phrases in text
  objects.

* ARexx support.

ARexx is a program, by William Hawes, that allows programs to communicate
with each other.  UltraCard can both send ARexx commands to other programs
as well as listen for commands to UltraCard from other programs.  This all
means that you can create a custom environment which can allow the use of
many programs together at a single click of the mouse.

Terminology Note:

We use the terms OBJECT and BUTTON interchangably.  This is because most
objects that you create using UltraCard perform some action when you click
the mouse over them, i.e. "pushing the button".  In reality, a button is
just a simple form of an object and all objects, including data entry
fields, can take action when "pushed".

                6

                        GETTING STARTED

Copying your distribution disk

UltraCard is not copy protected.  Please, since we have created the freely
distributable browser, spread the WORD not the SOFTWARE.  Your cooperation
is critical to the continued support and enhancement of the UltraCard
software.  Please make a copy of your distribution disk.

                7

Configuring UltraCard on Floppy Disks

UltraCard comes complete and ready to use.  We have not installed the
UltraCard program on a version of the standard Workbench disk.  So to use
UltraCard you should start your Amiga from your standard Workbench and then
either put the UltraCard disk in the drive or copy the files to your hard
disk (if present).  If you wish to move UltraCard to another floppy
configuration you need the following minimum set of files to use UltraCard:

    UltraCard - the program
    Stacks/Control Room - the default stack

    If you want to use the Help key you need:
    Stacks/Help - the UltraCard help stack.

Configuring UltraCard on Hard Disks

Using Ultra CArd with a hard disk allows you to use even more capabilites
that are built into the software.

In particular, the IFF/PAINT menu item can execute a program to change the
backdrop pictures.  You can set the name and path of this program using the
PAINT: button in the ControlRoom stack.  Using this with a hard disk is
easy.

To install UltraCard on a hard disk simply copy the program icon and the
Stacks drawer to your hard

                8

disk.  When you run UltraCard it looks for the stacks in a drawer (on a
logical device or floppy named ULTRA:) called STACKS.

The UltraCard ControlRoom allows you to change the search path for stacks.
Examine and modify the Preferences frame.  Simply click on the MORE...
button on the first frame of the ControlRoom and then click on the EVEN
MORE... object on the next frame displayed.  Then click on the multi-line
object at the bottom of the screen to edit the paths.  When you have the
paths set up the way you want then click on the PATHWAYS button to make
these path changes permanent.

Put the following line in your s:startup-sequence file to use UltraCard on
your hard disk:

    ASSIGN ULTRA: DH0:

This assumes that you put the STACKS directory on the top level of your
hard disk.

Running UltraCard from the CLI

If you want to run UltraCard from the CLI you MUST make sure your stack is
at least 15,000 bytes big.  Type STACK at the CLI prompt to see the current
setting.  The default for AmigaDOS is 4000.  To change the stack size type:

    STACK 15000

                9

Loading UltraCard

If you run UltraCard from the Workbench then simply double click on the
program icon (or click and select Open) to run the program.

If you want to run UltraCard from the CLI/Shell you MUST MAKE SURE THAT
YOUR STACK IS AT LEAST 10,000 bytes big.  If you don't understand this
requirement refer to a manual on the AmigaDOS CLI.

UltraStacks are saved with icons and an icon may be opened which
automatically starts the browser version of the program.

                10

LEAVING ULTRACARD

When you are done using the UltraCard simply choose QUIT from the PROJECT
menu to return to the Workbench or CLI.  If you have run other programs
(via the WORKBENCH statement) UltraCard will wait until all these other
programs are complete before quitting.  Don't worry if this seems confusing
at first it will become clear as you become more proficient in using
UltraCard.

                11

The ControlRoom Stack

                PROGRAMS    STACKS

        IDEAS        MORE...

The Starting point and the Return.

The ControlRoom stack is the first stack you use when using the UltraCard
program.  From this stack you can open other stacks, run programs, and ask
for help.

Most stacks contain a miniature picture of the ControlRoom screen display.
By clicking on this picture the current stack will close and the
ControlRoom will open.  In this way, the ControlRoom acts as a "Grand
Central Station" for UltraCard providing a consistent, dependable launching
point each time the program is used.

                12

You will find a return-to-ControlRoom button in the sample button stacks
which you can copy and paste into your own stacks.

                13

Loading Other Stacks

On the ControlRoom opening screen you can see the four smaller "screens".
Each of these screens has one or more "buttons" on which you can click.  To
see where the buttons are hold down the Left ALT key and then press the
Ctrl Key.  The location of all currently active buttons is shown by a
dotted line rectangle around each object.

Click on the button named "Stacks" and the current frame will close and the
SELECT-A-STACK frame will appear.  On this frame are names of some of the
various sample stacks included with UltraCard.  Simply click on the stack
you wish to open and it will be done.  In the Manual stack it explains how
to add icons to this frame for your stacks.

You can, at any time, choose Open Stack from the Project menu.  This will
display a file selector from which you can pick a stack file.

Setting the Pathways

UltraCard normally searches the ULTRA: directory and then the ULTRA:STACKS
directory for opening stacks.  Clicking on the More... button on the first
screen of the ControlRoom stack and then the Even More... button you can
then click on the

                14

UltraCard Operating Basics

You need to know the basics of navigation through the UltraCard universe to
use the Control Room and the on-disk Manual, Tutorial and Help stacks.
Once you have read this section you can begin using the disk based
information and return to the manual once you have begun exploring
UltraCard.

UltraCard operates like other Amiga applications in the following ways:

    1. The left mouse button is used to make non-menu selections.

    2. The right mouse button is used to make menu selections.

    3. The UltraCard screen can be dragged top-to-bottom.  If the
       screen title bar is visible.  To toggle the title bar, press
       F5.

    4. UltraCard is a well behaved multi-tasking application and can
       be run with other Amiga software simultaneously.

       When UltraCard is idle it takes NO system time as it is
       waiting for a mouse click.

    5. UltraCard screens have, while not always visible, front-to-back
       gadgets and back-to-front gadgets.  In some cases you may

                15

       have to turn the title bar on (press F5) to access the drag
       bar or depth gadgets.

    6. UltraCard is fully compatible with both NTSC and PAL systems.

                16

Objects

The fundamental building block of UltraCard is the object.  The object can
appear as a button, a data entry field, a multi-line field, scroll arrows,
a bitmap image or combinations of the above.

We often times use the words button and object interchangably as clicking
on most objects acts like the push of a button.

Some objects, like data entry fields, allow you to type data which is kept
inside the object.  This data can be used by an UltraTalk script to print,
calculate or make decisions.

                17

Browsing

Moving through an UltraCard stack is called BROWSING.  Your switch, or
NAVIGATE, between frames using the selections from the GO menu or by using
the arrow or Right-Amiga keyboard shortcuts.  Often there are objects on a
frame which respond to the mouse.

Selecting Objects with the mouse

You select an object, triggering an action, by clicking the left mouse
button with the mouse pointer (the pointing hand) over the object.  Like
standard Amiga gadgets you must release the mouse button with the mouse
pointer over most objects for action to take place.

Like gadgets, there are exceptions.  Some objects respond immediately when
the mouse button is clicked down.  Some objects highlight by inverting
their contents when clicked and some draw an outline.  Some even cause
other, invisible fields, to appear when the mouse is held down and
disappear when it is released.  You have full capability to create all
these types of responses using UltraCard.

                18

Changing Frames

Most UltraCard stacks are made up of multiple frames of information.
Moving between these frames, or navigating, is one of the fundamental
skills needed to use UltraCard.  As you move from frame to frame there are
a variety of visual effects you will see including wipes, fades, slides and
more.  Look at the appendix for a listing fo the available visual effects.

Using the GO Menu

The GO menu allows you to move to the first, next, previous or last frame
in a stack.  You can select the menu items or use the Right Amiga shortcuts
which correspond to the legends on the numeric keypad keys.

                19

Using the Arrow Keys

The arrow keys on the keyboard can also be used to move about in the
UltraCard stack as shown below:

    Up Arrow    = First Frame
    Down Arrow    = Last Frame
    Right Arrow    = Next Frame
    Left Arrow    = Previous Frame

(Note for experienced users:  You can, by writing handlers for the
UP.ARROW, DOWN.ARROW, LEFT.ARROW and RIGHT.ARROW messages, intercept the
standard meaning of the arrow keys.  You can also interpret the shift and
control keys when pressed with an arrow.  An example of this is in the
Ultradex stack in which we supply handlers for the RIGHT.ARROW and
LEFT.ARROW messages so that frame switching is done without visual effects
to increase the speed of flipping through the names in the stack).

Going BACK

After you have been moving from frame to frame you can use the Go/Back menu
item (or Right-Amiga-B shortcut) to retrace your steps.  Each time you
select Go/Back the frame you viewed before the currently visible frame will
be displayed.  The BACK list has a limit of 25 frames.

                20

Using the Recent Frame Selector

While using Go/Back is useful for navigating a short distance back, the
Recent Frame selector allows you to select, at random, any of the last 25
UNIQUE frames you have seen.  These can be in a single or in multiple
stacks.  Choose Go/Recent from the menu and then select the desired from
the selector.

                21

Accessing the Intuitive Technologies BBS

We maintain a 24-hour BBS system containing UltraCard stacks, 3rd-party
demonstration stacks and a Question & Answer database.  The phone number
for the BBS is:

[phone]

                22

Distribution of the Browser

On your UltraCard disk is a program called UCBrowser.  This is a special
version of UltraCard which cannot modify stacks but can read and navigate.
This program is freely redistributable (BUT NOT PUBLIC DOMAIN).  This
program you can give to your friends, with your favorite stack.

If you are a commercial venture and wish to create stacks, such as help
files, for your firm please contact us at Intuitive Technologies before you
distribute Browser.  it is still free, we just want to make sure that
everyone distributing the Browser always has the current version.

                23

                 UltraTalk Language Specification

INTRODUCTION

To the reader: This is a specification of UltraTalk.  It is not a tutorial.
We have included all statements, messages, and global variables as well as
examples of each.  To edit the script for an object, click on the object
and select SCRIPT.. from the PROPERTIES menu or double click on the object.
If the object moves unexpectedly you can put the object back in its
original position by choosing UNDO from the EDIT menu (use Right-Amiga-Z).

An example of the UltraTalk script editor is shown below.  Check the Editor
Menus frame in the HELP stack for information about using the Editor.

GENERAL SYNTAX RULES

UltraTalk is a line oriented language.  Comments begin with two dashes and
lines are continued by placing an exclamation point (!) at the end of the
line.  Capitalization is not significant and multiple spaces and tabs are
treated as a single space.  Statement labels (see GOTO below) are denoted
by a leading AND trailing colon (e.g. :MYTOPOFLOOP:).

                24

Spaces are not necessary between operators (e.g. A + B is the same as A+B).
Variables are significant up to and may not be longer than 256 characters.

Script text is stored separately from the actual executable script code so
there is no execution time penalty for heavily commented code.  Variable
name length is only significant (as it relates to execution time) if the
names exceed 20 characters in length.

DATA VALUES

Data values in UltraTalk are always stored as character strings.  If a
computation is indicated (e.g. ADD a TO b) the strings are converted to
numbers, the calculation performed, and the number converted back to a
string.  This makes the job of creating scripts much easier since you don't
have to worry about variable typing.

OBJECTS, FRAMES, BACKDROPS & STACKS

UltraCard stacks are built from only three fundamental building blocks: the
Object, the Frame and the backdrop.

A stack consists of at least one backdrop and one frame and zero or more
objects.  A Backdrop and a Frame are nearly identical.  A Backdrop can be
thought of as a common background over which one or more frames are drawn.
Both a Backdrop and a Frame can

                25

"contain" zero or more objects.  These objects take the form of "buttons",
data entry fields or multi-line values.  They can be solid or clear, filled
with colors or graphics or proportional gadgets (sliders) and can have a
name which can be (optionally) displayed inside or outside the object.

A graphic representation of the relationship between a backdrop and frames
is shown below.  We use the UltraCard help stack as an example:

HELP stack (consisting of 2 bdrops, 8 frame)

BIRD'S EYE VIEW OF A STACK:

Backdrop 1
  Frame 1 (main menu)
Backdrop 2
  Frame 2 (browse menus)
  Frame 3 (modify menus)
  Frame 4 (objects)
  Frame 5 (keyboard)
  Frame 6 (UltraTalk statements)
  Frame 7 (Functions)
  Frame 8 (Editor menus)

A more detailed diagram of the first three frames is shown below:

                26

+--------------------------Backdrop Level
|
|  +------------------------ Backdrop Object Level
|  |
|  |   +------------------------Frame Level
|  |   |
|  |   |   +-----------------------Frame Object Level
|  |   |   |
|  |   |   |

Backdrop 1 (with picture of boxes & lines)
....
.. Frame 1
....
... About Object
... Menus Object
... UltraTalk Object
... Keyboard Object
.   .. Objects Object
Backdrop 2 (blue background)
. Back to first arrow (Graphic fill)
.. Frame 2 (Browse menus)
....
... Project Menu (graphic fill)
... Edit Menu    (graphic fill)
... Go Menu      (graphic fill)
... Browse Menus (name shown inside)
... Modify Menus (name shown inside)
....
.. Frame 3  (Modify menus)
....
... Edit Menu       (graphic fill)
... Properties Menu (graphic fill)
... Contents Menu   (graphic fill)
... Editor Menus    (name shown inside)
... Modify Menus    (name shown inside)

                27

As you can see each frame sits atop a backdrop and multiple frames can
share a single backdrop.  The backdrop contains the background IFF picture
and any objects common its child frames (such as the Back to First arrow
shown above).

MESSAGES

The central idea of UltraCard and consequently UltraTalk is the message.  A
message is simple a "signal" resulting from either an action by the user or
an internally generated condition detected by the program, such as a time
counter, signifying that something has happened.  Each of the components of
the UltraCard program and the backdrop, frame and objects of your UltraCard
stack "listen" for messages that apply to them.  As each object is
"activated" it inserts itself into the listening list.  When a message is
"sent" it is simply given to the first listener in the list who checks to
see if it si the message that that listener is waiting for.  It is not then
the message is given to the next listener in the list and so on until the
message either "falls out the bottom" or one of the listeners determines
that the message is to be processed and handles the request coded into the
message.  This is why listeners are also called "message handlers".

                28

MESSAGE HIERARCHY

As mentioned in the previous paragraph, there is a definite hierarchy to
the listener list.  A message, when sent, is given to the topmost listener
(or handler) on the list who determines if the message is of interest.  If
it is not applicable to that handler (e.g. not a click in the button
associated with that handler) the handler passes the message on to the next
handler in the list.

It is this hierarchy of messages that makes it possible to write complex
programs using UltraCard.  Mouse clicks, key strokes, menu selections, etc.
all generate messages.  Only the handler listening for a specific message
actually takes action on any given message.  The hierarchy shown below
shows how the handlers are ordered.

FRAME OBJECTS
  FRAME
    BACKDROP OBJECTS
      BACKDROP
        STACK
          CONTROLROOM STACK
            ULTRACARD

What this means is that when an action occurs, such as a mouse click, it is
sent to the topmost Frame object,

                29

which examines it to see if it is within the object's rectangle, if not
then it passes it to the next layer down, and so forth until it either
finds a handler that processes the message or UltraCard handles the mouse
click directly (e.g. when you are creating objects).  Any handler can pass,
process or process and then pass a message. (See the PASS statement).

MESSAGE TRANSFORMATION

As you become more familiar with UltraCard you will find that you write the
script for an object as handlers for the SELECT.UP and SELECT.DOWN
messages.  These messages are created by the built-in button object handler
that processes the CLICK.DOWN and CLICK.UP messages generated by the
internal program code.  When the button object detects a mouse click inside
an object it sends a SELECT.DOWN/SELECT.UP directly to the script handler
for your object.  This is done so that your script didn't have to check
each mouse click to see whether the click was in the object, the UltraCard
program does that for you.  This means that when your object receives a
SELECT.DOWN or SELECT.UP message that you are already guaranteed that the
mouse was clicked inside your object.

                30

MESSAGE HANDLERS

We have talked about objects, messages and handlers.  A message handler is
an UltraTalk subroutine that processes a specific message.  A message
handler uses the syntax shown below:

    MESSAGE.NAME:
     -- your code
         -- goes here
    END_MESSAGE.NAME

The name of the message handled by the handler is put at the beginning and
followed by a colon.  Your script code follows immediately after that
(blank lines are ignored) and you put a line beginning with "END_" at the
end of your handler.  It is convention but not required to put the name of
the message after the underscore.

Most message handlers that you will code will be those to handle messages
generated by the UltraCard program such as SELECT.DOWN and SELECT.UP or
timer messages such as SECOND.TICK, etc.  You can also write subroutines
for your own messages that you design.  Using this mechanism you can create
your own built-in functions:

                31

    MY.SUBROUTINE:
      put parm(1) + parm(2) into answer
          return answer
    END_MY.SUBROUTINE

    SELECT.DOWN:
      put MY.SUBROUTINE(5,3) into result
      say result
    END_SELECT.DOWN

All statements in UltraCard are simply messages that are sent and handled
by the built-in handlers.  For example, when you code a PUT statement it
simply sends a message "PUT" and whatever handler gets and processes that
message first implements the PUT statement.  Therefore any name you create
for a built-in function simply sends that name as a message (see the
example above).  Built-in functions can have up to 10 parameters.

VARIABLES -- Local & Global

Within your message handlers you can create temporary "containers" for
strings and numerical values just by naming them where necessary, such as
the target of a PUT statement:

    PUT 3 into COUNTER

This declares a "local" variable named counter.  Local variable only exist
while the handler is being executed

                32

and are discarded when the END_ statement is reached.

If you want to communicate between handlers to save values between
execution of a handler you need to use a "global" variable which is created
using the GLOBAL statement.  Global variables exist from the time you
create them until you close the stack.

There are a number of GLOBAL variables that are predefined by the UltraCard
program.  You will find a list of these variables, their default values and
the actions they control listed later in this document.

STATEMENT Handlers

Each UltraCard statement performs a task for you in a script.  The first
item on a line is the name of the statement.  This is followed by a blank
if there are any parameters and the parameters are separated by blanks and
sometimes optional keywords.

    Optional items are shown in braces { }

    Expressions are shown as <expr>
      and can be any string or numeric
        expression as appropriate

    The word "THE" is always ignored if
      written separately to make statements
      more readable:

                33

      add THE cost to THE result

    could also be written:

      add cost to result

The statement handlers are described later in this document and in the HELP
stack.

FUNCTION Handlers

There are a variety of built-in functions available in UltraTalk.  They
allow you to manipulate strings, do arithmetic conversions, take the
absolute value of numeric numbers, etc.

Built-in functions, as well as user defined functions, can be used as part
of an expression anywhere an expression is legal.  Parameters to the
function are passed in parentheses and separated by commas:

    PUT WORD (1, line.var) INTO word.temp

                34

Operators

UltraTalk expressions combine constants and variables using the following
operators:

    Arithmetic Operators

    +        Addition
    -        Subtraction
    *        Multiplication
    /        Division
    ^        Exponentiation (e.g. 2^3)
    Unary -        Negation
    Unary +        (allowed by ignored)
    %        Remainder from
            integer divide
            (NOTE: The arguments
            are limited to
            32 bit precision for
            this operator)

                35

    Relational Operators

    =        Equality
    >        Greater Than
    <        Less Than
    >=        Greater Than or Equal
    <=        Less Than or Equal
    <>        Not Equal
    is        Equality
    contains    True if right string
            is contained
            in left string

    in        True if left string
            is contained
            in right string

    Boolean Operators

    NOT        Logical NOT
    |        Logical OR
    &        Logical AND
    OR        Logical OR
    AND        Logical AND

    Character Operators

    &&        String Concatenation

                36

                        UltraTalk Statements

Each statement is described in three sections.  First the syntax of the
statement is given.  If this syntax takes multiple lines each subsequent
line is indented but you do not do this when typing in the statements into
the program.  Following the syntax is a paragraph describing the function
of that statement and finally an example of using the statement is given.

Optional arguments are put in braces {  }

When one option MUST be chosen the vertical bar means include one of the
options.  (e.g. (ON | OFF) means use ON or OFF but one is required.

<expr> means any valid UltraTalk expression.

Sometimes names are used instead of <expr> but the meaning is the same.

Remember, case is never significant EXCEPT inside quoted strings and then
not for comparisons.

                37

Syntax:
SAY    <string-expression>

Function:
    Speaks the string through the Amiga's translator and narrator
facilities (synthesized speech).  If the first character of the string is a
tilde (~) then the string is not run through the translator but is assumed
to already be in phoneme form suitable for the narrator device.

Example:
    SAY "Hello from UltraCard"
    SAY ""~PUH4L DAW2N MEH4NYUW3S"
    -- (says "PULL DOWN MENUS")

                38

Syntax:
JUMP {TO} FRAME {ID} <expr1)
     {OF {STACK} <expr2>}}
     {WITH} {EFFECT}

Function:
    Causes the UltraCard current frame to be changed to the specified
new frame.  The new frame can be in the same stack or a different stack and
if the screen resolution is the same you can use a visual effect by
specifying the EFFECT keyword.  <expr1> is either the ID number (not
sequence in stack number) or name of the new frame.  See the section
describing visual effects for more information about using EFFECT.  <expr2>
is the name of the stack and is normally in quotes.

<expr1> can also be one of the following keywords:

    NEXT
    PREV
    PREVIOUS
    FIRST
    LAST

which specify the frame by its relationship to the current frame or within
the stack.

Example:

Jump to next
JUMP TO FRAME 3 OF STACK "HELP" WITH EFFECT

                39

Syntax:
PUT <expr> {INTO | BEFORE | AFTER } <dest>

Function:
    Stores the value of <expr> into, before or after the variable
specified by <dest>.  Using BEFORE or AFTER results in a prepend or
appending operation being performed.  Using INTO discards the old contents
of <dest> and replaces it completely with the new value.

Example:
    PUT 3 into counter
    PUT "Name" into value1
    PUT "BBB" into value2
    PUT "AAA" before value2
    PUT "CCC" after value2
    -- results in value2 "AAABBBCCC" if
    -- value 2 is NOT multi-line
    -- If value2
    -- is an object with the Multi-line
    -- property TRUE then the value2 will
    -- be equal to THREE separate lines:
    -- AAA
    -- BBB
    -- CCC

                40

Syntax:
CYCLE.COLOR {OFF | ON <expr1>, <expr2>, <expr3>}

Function:
    Turns color cycling off and on.  <expr1> is the low color number to
start the cycle, <expr2> is the high color number to end the cycle and
<expr3> is the number of times per second to cycle.

Example:

    -- cycle 2->5 10 times per second
       CYCLE.COLORS ON 2, 5, 10

    -- turn color cycling OFF
       CYCLE.COLORS OFF

                41

Syntax:
SLEEP

Function:
    Puts UltraCard to sleep by closing its screen and releasing as much
memory as possible so that you can run other programs.  When the other
program quits you normally use the WAKE.UP statement to restart UltraCard.
If you accidentally put UltraCard to sleep and forget the WAKE.UP statement
you can wake it up by holding down the CTRL, Left-Shift and Left-Alt keys
and clicking the mouse button

Example:
    --- sleep to give up memory
    SLEEP
    WORKBENCH "DeluxePaintIII:DPAINT"
    --- and then wake.up when Dpaint done
    WAKE.UP

                42

Syntax:
WAKE.UP

Function:
    Used after the SLEEP statement to "wake up" UltraCard.  Reallocates
memory and reopens the UltraCard screen.

Example:
(see SLEEP)

                43

Syntax:
SAVE.BRUSH object TO <filename>

Function:
    Saves the contents of a graphic filled object as an IFF brush file.
Saves the contents of the brush based upon the CURRENT dimensions of the
object.  Graphic objects acquire a maximum size when they are created but
can be "shrunk" so that only a portion of the object is visible either
manually or under script control.  They can never be made bigger than their
original size.

Example:

    -- save a button as a brush
    SAVE.BRUSH object.23 TO !
        "brushes/brush1"

                44

Syntax:
GRAPHIC.FILL object FROM <filename>, <1>, <t>, <w>, <h>

Function:
    Loads an object from an IFF picture or brush.  It changes the fill
property of the object to "Graphic" if it is not already set that way.  If
the object is a BRUSH then you can specify l, w, t, h as 0, 0, 0, 0
otherwise they represent the left pixel, top pixel, width in pixels and
height in pixels of the region you wish to extract from the IFF picture to
insert into the object.

Example:
    -- get user's picture from IFF file
    GRAPHIC.FILL picture.obj FROM !
        "pict", 0, 0, 100, 100

                45

Syntax:
SET.SCRIPT {OF} {STACK | FRAME | BDROP} TO <expr>

Function:
    This statement allows you to set the script of the specified level
from a multi-line value.  Don't forge to put in the linefeed characters
between the lines if you create the value from a script only.  The script
code so changes is not activated until the level being modified is exited
and then re-entered.  This is most often during scripts which create other
stacks.

Example:
    -- set the frame script of a stack
    -- under construction
    SET.SCRIPT OF FRAME TO !
      "FRAME.ENTRY: \OA" && !
         "  SAY Here.I.Am\OA" &&
         "END_FRAME.ENTRY\OA\OA"

                46

Syntax:
MENUS {ON | OFF}

Function:
    UltraCard menus may be turned on and off using this statement.  You
would want to turn them off to prevent the user from modifying the stack.
When the menus are turned off clicking on the right mouse button is
ignored.

Example:
    -- Make sure we have control
    MENUS OFF
    -- perform some work
    MENUS ON

                47

Syntax:
SERIAL.OPEN {<baud-rate-expression>}

Function:
    Opens the serial port for reading and writing.  If
<baud-rate-expression> is missing the last rate set is used.

Example:
    -- Prepare to talk to laser disk
    SERIAL.OPEN 9600

                48

Syntax:
SERIAL.CLOSE

Function:
    Closes the serial port which allows other programs to use it.

Example:
    -- close the serial port so I can print
    SERIAL.CLOSE

                49

Syntax:
SERIAL.WRITE  <output-expression>

Function:
    Writes data to the serial port.  There are two global variables,
SERIAL.PREFIX and SERIAL.SUFFIX that are prepended and appended to the data
respectively before it is output.  Normally these are empty but, for
example, most laser disk players want a control-B (STX) "\02" at the
beginning and a control-C (EXT) "\03" at the end of the command string so
these variables can be used to save having to code those characters for
each write.

Example:

    -- output string to laser disk (hard way)
    SERIAL.WRITE "\02" && "PF" && "\03"
    DELAY 20    -- wait 2 seconds
    SERIAL.WRITE "\02" && "PR" && "\03"

    -- output strings to laser disk (easy way)
    PUT "\02" into SERIAL.PREFIX
    PUT "\03" into SERIAL.SUFFIX

    SERIAL.WRITE "PF" -- play forward
    DELAY 20      -- wait 2 seconds
    SERIAL WRITE "PF" -- play reverse

    -- both examples do the same thing

                51

Syntax:
SERIAL.FLUSH

Function:
    This statement flushes any data present in the Amiga's serial
device buffer.  Useful to use before SERIAL.READ to make sure the
characters you get are "fresh".

Example:

    -- get some new characters
    SERIAL.FLUSH
    SERIAL.READ 15 TIMEOUT 250

                52

Syntax:
MOVE.SCREEN <expr>

Function:
    This statement moves the UltraCard screen to a specific pixel line
on the display.  It can be used to partially reveal a screen underneath
UltraCard such as the workbench.

Example:
    -- move our screen down, reveal workbench
    MOVE.SCREEN 180        -- 20 pixels from bottom
    -- move our screen back to the top
    MOVE.SCREEN 0

                53

Syntax:
SCREEN.TITLE <expr>

Function:
    The UltraCard screen normally has its title bar hidden from view so
that you can create full-screen applications.  You toggle the title bar on
and off using the F5 function key or by sending the KEY.F5 message.  The
screen title bar, when visible, normally displays the UltraCard version
number but you can change it to display any message you wish.

Example:
    -- Tell the user about our stack when
    -- the about button is clicked
    SCREEN.TITLE "My Stack -- Version 1.0"
    KEY.F5        -- Turn the title bar on
    DELAY 20    -- for two seconds
    KEY.F5        -- and turn it back off

                54

Syntax:
CHANGE {.LINE | .WORD | .ITEM} <n> OF <var> TO <expr>

Function:
    This statement allows you to make a substitution in a multi-line
text value.  You can change a whole line, a word or an item.  An item is
separated by commas and words are separated by white space.

Example:
    -- change the 4th word on
    -- the line to "BLACK" from "WHITE"
    PUT "THE COW WAS WHITE" into value
    CHANGE.WORD 4 of value to "BLACK"
    -- value now contains:
    -- "THE COW WAS BLACK"

                55

Syntax:
Choose From <v1> {SORT}

Function:
    This statement displays a list selector containing the values from
the multi-line expression <v1>.  The SORT keyword, if specified, sorts the
values in the list prior to display but does not change the value of <v1>.
The result of the choice is in the global variable IT.  If no choice is
made then IT contains the empty string "".

Example:
    -- ask the user
    CHOOSE FROM "RED\OAGREEN\OABLUE"
    -- displays in stated order, RED 1st
    CHOOSE FROM "RED\OAGREEN\OABLUE" SORT
    -- displays in sorted order BLUE 1st
    -- now IT contains the results

                56

Syntax:
LOAD.SOUND  <filename> AS <soundname>

Function:
    This statement preloads a digitized sound file into the Amiga's
CHIP memory (i.e. that memory directly accessible by the specialized DMA
chips).  It assigns the sound a "soundname" which can be used for
subsequent reference to the sound.  Normally soundnames are shorthand
versions of the filename and if they contain only letters, numbers, periods
and underscores do not need to be put in quotes.

Example:
    -- load our sounds
    LOAD.SOUND "DH0:SOUNDFILES/BEEP" as BEEP
    LOAD.SOUND "DH0:SOUNDFILES/SQUAWK" as !
        SQUAWK

                57

Syntax:
UNLOAD.SOUND <soundname>

Function:
    This statement removes a preloaded sound from CHIP memory therefore
making CHIP memory available for other uses such as other sounds or display
screens.  When UltraCard quits all preloaded sounds are unloaded
automatically.  They are NOT unloaded when you open a different stack
unless you explicitly unload them.

Example:
    -- unload our sounds and make more CHIP
    -- memory available
    unload.sound squawk
    unload.sound BEEP

                58

Syntax:
WAIT.SOUND <soundname>

Function:
    This statement causes UltraCard to pause until a sound that was
played using the ASYNC option of the PLAY statement (see PLAY) is finished.
 In this way you can synchronize the displays of your stack with the
duration of the sound.  If the sound was not played with ASYNC no action is
taken.  You MUST use either with WAIT.SOUND or STOP.SOUND with sounds
played using ASYNC in order to be able to play them multiple times as it
releases system resources used for playing sounds.

Example:
    -- play a sound, rotate the ball and
    -- then wait for the sound to complete
    play long.sound async
    for i=1 to 10
        cursor wait
    endfor
    wait.sound long.sound
    cursor ready

                59

Syntax:
STOP.SOUND <soundname>

Function:
    This statement causes a currently playing sound to stop
immediately.  This only works on sounds played using the ASYNC option of
the PLAY statement.

Example:
    -- play a sound
    -- but only part of it, the sound is 30
    -- seconds long but we'll only play 20
    -- seconds of it
    play long.sound async
    delay 200 -- 20 second delay
    stop.sound long.sound

                60

Syntax:
Play {SOUND} {FROM} <sound-file-name>
     {RATE <rate-expr>}
     {VOLUME <loudness-expr}
     {REPEAT <times>}
     {ASYNC}

Function:
    This statement plays digitized sounds using the Amiga's DMA
hardware.  Sounds must be stored as IFF or FutureSound format.  Either
one-shot or 8SVX sounds may be used.  The RATE keyword allows you to vary
the playback rate and is specified in Hz.  The VOLUME keyword allows you to
vary the playback volume and ranges from 0 (quiet) to 64 (maximum
loudness).  The REPEAT keyword allows you to repeat the sound a fixed
number of times.  The ASYNC keyword allows you to continue executing while
the sound is being played.  This is often used in conjunction with
digitized speech to show a message on the screen simultaneously with the
sound.  ASYNC can only be used with preloaded sounds, see LOAD.SOUND.

<sound-file-name> is either a disk file name or the name of a preloaded
sound (see LOAD.SOUND)

                61

Example:
    -- play the sound normally
    Play "DH0:SOUNDFILES/BOGART"

    -- play it fast (record rate was 15000)
    Play "DH0:SOUNDFILES/BOGART" RATE 30000

    -- play a preloaded sound softly
    Play buzzer VOLUME 10

    -- play the buzzer 5 times
    Play buzzer REPEAT 5

    -- play a long sound and continue on
    Load.Sound "bogart.30sec" as bogie.long
    Play bogie.long ASYNC
    SHOW.MSG "Bogart was a movie actor" !
        for 5 seconds
    Wait.Sound bogie.long
    Unload.Sound bogie.long

                62

Syntax:
CLI <prog-name> {INPUT file} {OUTPUT file}

Function:
    This statement allows you to run external programs as if they were
run from the AmigaDOS CLI (command-line-interface).  The <prog-name>
expression should contain the name of the program and all command line
arguments.  The INPUT clause allows you to specify I/O REDIRECTION, not an
input file name.  The OUTPUT clause similarly is related to I/O
REDIRECTION.

Example:
    -- if you would type: LIST >RAM:FOO #?.c
    -- use:
    CLI "LIST #?.c" !
        INPUT "NIL:" !
        OUTPUT "RAM:FOO"
    -- Note: some programs require input and
    -- output streams so you must use them
    -- like:
    CLI "program" INPUT "NIL:" OUTPUT "NIL:"

                63

Syntax:
WORKBENCH <prog-name> {INPUT file} NOWAIT

Function:
    This statement allows you to run external programs as if they were
run from the Workbench.  You can pass a file name to the program just as if
you had double clicked on a data file icon and automatically started the
program.  If you use the NOWAIT keyword the program will be started and
UltraCard will continue.  A "program handle" will be stored in the global
variable "IT".  You can save this handle if you need to synchronize with
the program later by using the WAIT statement (see below).  Programs
started in this way (asynchronously) must complete before UltraCard can
quit.

Example:
    -- start DeluxePaint from UltraCard
    -- Note: DPAINT cannot accept cmdline
    -- arguments for files so you must use
    -- it from the WORKBENCH statement

    WORKBENCH "DH0:DPAINT3/DPAINT" !
        INPUT "mypic"

    -- another example, make UC sleep, start
    -- DPAINT, wait for it to finish and
    -- wakeup again
    SLEEP
    WORKBENCH, "DeluxePaintIII:DPAINT" NOWAIT
    WAIT FOR IT
    WAKE.UP

                64

Syntax:
WAIT {FOR} <prog_handle>

Function:
    This statement is used in conjunction with the WORKBENCH statement
to wait for a program started by the WORKBENCH statement to complete.  When
the WORKBENCH statement starts a program using the NOWAIT keyword it puts a
"handle" into the global variable IT.  You can put the contents of IT into
a global variable and then wait for the program to finish later.  You must
use the result from the WORKBENCH statement as an argument to WAIT.

Example:
    (see WORKBENCH statement)

                65

Syntax:
GetFileName {FROM <dir>} {PROMPT <str>} {INTO <container>}

Function:
    This statement displays the UltraCard file selector and allows the
user to choose a file with the mouse.  If no file is selected the result is
"NO_FILE".  The FROM clause allows you to specify a starting directory.
The PROMPT clause allows to set the title of the file selector window.  The
INTO clause allows you to direct the file name to be placed into a
variable.  If the INTO clause is missing the result is stored in the global
variable IT.

Example:
    -- get a stack name
    GetFileName FROM "ULTRA:STACKS" !
        PROMPT "Pick a stack" !
        INTO stack.name
    IF IT is "NO_FILE"
        say "You didn't pick a file"
    ELSE
        say "you picked: && it
    ENDIF

                66

Syntax:
IF <expression> {THEN}
    statements
{ELSE
    statements}
ENDIF

Function:
    This statement allows conditional execution of blocks of script
code.  The expression is evaluated and then examined.  If it is non-Zero
then the statements between the IF and the ENDIF are executed otherwise
they are skipped.  An optional ELSE statement can be used.

Example:
    put 1 into A
    put 2 into B
    if A > B
      say "A is greater than B"
    else
      say "A is less then B"
    endif

    if it is 0
      say "zero found"
    endif

                67

Syntax:
Set {THE} <property-expr>
   OF <object-name> TO <expr>

Function:
    Each object in UltraCard has a variety of attributes that are
called "properties".  These include the objects location, size, file,
value, shape, etc.  Each of these properties can be manipulated by the
menus in Modify mode or by the SET statement.

Listed at the end of this document are the names of the properties and the
ranges of values they may take on.  You can use the GET statement to
retrieve the current value of a property and then use the SET statement to
the value of property to a new value.

There are two special properties and two special object names that are used
to signal to UltraCard whether to keep modifications after using SET.  The
properties are called MODIFIED.OBJECTS and MODIFIED.GRAPHICS and the
objects are "THE.FRAME" and "THE.BACKDROP".  They must be specified as
shown as THE is part of the name.

Example:
    -- make some temporary changes to an object
         set the fill.color of object.1 to 3
       set the name of object.2 to "Stop"

    -- and now make these changes permanent
       set the modified.objects of the.frame to 1
    -- Note: If you do not put in a statement

                68

    -- like the one above the properties will
    -- revert to the original values when the
    -- frame is closed (i.e. you jump to another
    -- frame)

                69

Syntax:
GOTO or GO TO <label>

Function:
    This statement changes the order of execution of script language
statements.  You specify the statement label on a line by preceding and
trailing colon.

Example:
    -- demo of GOTO statement
    if a > b then
      goto not.now
    endif
    --
    -- some other statements
    --
    :not.now:
    -- execution continues here after
    --the goto

Syntax:
GLOBAL <varname> {,varname}

Function:
    As previously described variables are only temporary unless
declared global.  This statement allows you to create global variables.  If
the variable is already created then this statement has no effect.

Example:
    -- declare some variables global
    GLOBAL flag, total, credit.value

                71

Syntax:
ADD <expr> TO <dest>

Function:
    This statement adds the value of <expr> to the value of the object
or variable <dest>

Example:
    put 3 into value1
    add 5 to value1
    -- now value1 contains 8

                72

Syntax:
SUBTRACT <expr> FROM <dest>

Function:
    This statement subtracts the value of <expr> from the value of the
object or variable <dest>.

Example:
    put 5 into value1
    subtract 2 from value1
    -- value1 now contains 3

                73

Syntax:
MULTIPLY <dest> BY <value>

Function:
    This statement multiplies the value of <expr> into the value of the
object of variable <dest>.

Example:
    put 5 into value1
    multiply value1 by 10
    -- value1 now contains 50

                74

Syntax:
DIVIDE <dest> BY <expr>

Function:
    This statement divides the object or variable <dest> by the value
of <expr>.

Example:
    put 50 into value1
    divide value1 by 10
    -- value1 now contains 5

                75

Syntax:
GET <expr>
GET <property> OF <object>

Function:
    This statement performs one of two functions.  Without the OF
keyword it simply evaluates the value of <expr> and puts the results into
the global variable IT.  If the OF keyword is present then this statement
retrieves a specific property of an object and puts the value into the
global variable IT.

Example:
    -- Form 1 - evaluate expressions

    GET ABS(total) -- result in IT
    GET MY.SUBROUTINE(a,b,c)

    -- Form 2 - retrieve properties

    GET THE TOP.LINE of TEXT.AREA
    GET the LEFT.EDGE of OBJECT.1

                76

Syntax:
Lock.Screen

Function:
    This statement "locks" the screen so that further jumps and
property changes are not shown.  When all your changes are complete then
use UNLOCK.SCREEN to restore the screen to normal operation.  If your
script completes and UltraCard is ready to listen again for mouse clicks,
etc. the screen is automatically unlocked.  Note: As described in the
UNLOCK.SCREEN documentation, UNLOCK.SCREEN uses the current setting of
VISUAL.EFFECT and performs an effect when unlocking the screen.

Example:
    -- move an object and make it pretty
    lock.screen
    get the left.edge of object.1
    set the left.edge of object.1 to it+10
    unlock.screen

                77

Syntax:
Unlock.Screen

Function:
    Used with LOCK.SCREEN.  Unlock.Screen restores the visual display
from the current frame using the current setting of the global variable,
VISUAL.EFFECT.  If the screen was not locked this statement has no effect.

Example:
    -- demo lock & unlock
    -- this saves the current frame (PUSH)
    -- and jumps to another frame, changes
    -- the value of an object, and then POP's
    -- back and unlocks the screen.  Visual
    -- seen by the user is NOTHING even
    -- though there were two frame changes.

    LOCK.SCREEN
    PUSH
    jump to frame 5
    add 1 to counter
    POP
    UNLOCK.SCREEN

                78

Syntax:
PASS

Function:
    This statement causes the current message to be passed on down the
list of message handlers.  You would use this, for example, to process a
CLICK.DOWN message at the frame level and then pass it on to be handled at
the backdrop or stack level.

Example:
    -- click.down at frame level
    click.down:
         say "click at frame"
      pass -- so it can go to backdrop level
    end_click.down

                79

Syntax:
POP

Function:
    Within UltraCard there is a 25-level push/pop stack that you can
use to save a stack/frame location combination (using PUSHP and then return
to the saved location without the returning script knowing where you are
returning to.  For example, when you press the HELP key or choose HELP from
the GO menu, the current frame on the screen is saved in the PUSH/POP stack.
While you are in the HELP stack the KEY.F10 message is intercepted by a
stack-handler and executes the POP statement so that you can continue
working exactly where you were before you went to the help stack.

Example:
    PUSH -- save our current frame
    JUMP to FRAME 5 of STACK "MY.OTHER.STACK"

    -- when a POP statement is executed the
    -- frame containing this script will be
    -- shown again

                80

Syntax:
PUSH

Function:
    Save the current stack & frame on the PUSH/POP stack.  Later when a
POP statement is executed the current stack/frame combination will once
again be on the screen.  See the documentation for POP.

Example:
    -- example of POP
    POP -- return to stack that called us.

                81

Syntax:
RETURN <expr>

Function:
    All UltraTalk handlers can be called as a function and the RETURN
statement creates whatever value is to be returned.  You can get any
expression to call a function or use the GET statement.

Example:

    MY.SAMPLE.FUNCTION
        put parm(1) into value
        multiply value by parm(2)
       return value
    END_MY.SAMPLE.FUNCTION

    -- call my function
    GET MY.SAMPLE.FUNCTION(5,10)
    -- now IT contains the result of 50

                82

Syntax:
Send {TO object} message

Function:
    This statement sends an UltraTalk message.  It is most often used
to send a CLICK.DOWN/CLICK.UP message sequence to a button to simulate the
user clicking on the button.  If the TO clause is used then the global
variables MOUSE.X and MOUSE.Y are set to the location of the object before
the message is sent.

Example:
    -- simulate the user clicking on object.1
    SEND TO OBJECT.1 CLICK.DOWN
    SEND TO OBJECT.1 CLICK.UP

    -- This can also be used to send messages
    -- normally sent by the program
    SEND FRAME.ENTRY  -- Run it again

                83

Syntax:
ENTER.MODIFY

Function:
    You can create a stack that modified itself using the modify mode
of UltraCard.  This statement changes from BROWSE mode to MODIFY mode just
as if you had pressed F2 on the keyboard.

Example:
    -- go into modify mode
    ENTER.MODIFY

                84

Syntax:
EXIT.MODIFY

Function:
    This statement returns you to BROWSE mode.  If you are already in
browse mode it has no effect.  Normally this is used after ENTER.MODIFY.

Example:
    -- return to BROWSE mode.
    EXIT.MODIFY

                85

Syntax:
NEW.OBJ <name>, <1>, <t>, <w>, <h>
        {FRAME | BACKDROP}

Function:
    This statement, used only when you are in MODIFY mode, creates a
new object using the name, location (l=left, t=top) and dimensions
(w=width, h=height) you specify.  You must specify whether this is to be a
FRAME layer or a BACKDROP layer object.

Example:
    -- create new obj under program control
    NEW.OBJECT "button",10,20,50,25

                86

Syntax:
CUT

Function:
    This statement, used only when you are in MODIFY mode, copies the
currently selected object to the internal clipboard and then deletes the
object.  You may get the object back from the internal clipboard using
PASTE.

Example:
    -- check to see if there is a selection
    -- and then cut it to the clipboard
    -- SELECTION is a global variable which
    -- contains the ID of the object
    -- currently selected

    if selection is.not 0
        CUT
    else
        SHOW.MSG "No Object Selected"
    endif

                87

Syntax:
COPY

Function:
    This statement, used only when you are in MODIFY mode, copies the
currently selected object to the internal clipboard.

Example:
    -- check to see if there is a selection
    -- and then copy it to the clipboard
    -- SELECTION is a global variable which
    -- contains the ID of the object
    -- currently selected

    if selection is.not 0
       COPY
    else
       SHOW.MSG "No Object Selected"
    endif

                88

Syntax:
Paste

Function:
    This statement copies an object which has been placed on the
internal clipboard (using CUT or COPY) and puts it in the FRAME or
BACKDROP.  A Paste always pastes the object to the layer from which it was
Cut or Copy'd.  Paste always puts the object two (2) pixels lower and two
(2) pixels to the right of the original position.

Example:
    -- demo of the object Paste
    PASTE

                89

Syntax:
Clear

Function:
    This statement, used only when you are in the MODIFY mode, deletes
the currently selected object.  THERE IS NO UNDO of this operation.

Example:
    -- check to see if there is a selection
    -- and then delete it
    -- SELECTION is a global variable which
    -- contains the ID of the object
    -- currently selected

    if selection is.not 0
       CLEAR
    else
       SHOW.MSG "No Object Selected"
    endif

                90

Syntax:
SET.COLOR <color-num>,
     <Red>,<Green>,<Blue>
     <Save>

Function:
    This statement allows you to alter the color map of the current
screen.  <color-num> is a number from 0 to the max-number-of-colors minus 1
(e.g. 31 for a 32 color screen) and Red, Green and Blue are the RGB
components of the desired color.  The values may range fro 0 to 15.  If any
of them are equal to -1 then that color is not changed.  If the SAVE
keyword is specified then the BACKDROP is saved immediately with the new
color palette.

Example:
    -- change color 1 to white
    SET.COLOR 1,15,15,15

                91

Syntax:
SELECT.OBJECT <obj name>

Function:
    This statement, used only in MODIFY.MODE, selects an object by
name.

Example:
    -- select an object
    SELECT.OBJECT object.1

                92

Syntax:
DELAY (.1's of a second)

Function:
    This statement causes UltraCard to wait for the specified period of
time.  The count value given is in 1/10th of a second so to delay for 1
second use DELAY 10.

Example:
    -- Delay for 1/2 second
    DELAY 5

    -- Delay 10 seconds
    DELAY 100

                93

Syntax:
ANSWER <expr> WITH <pos> {, <neg>}

Function:
    This statement displays a requester on the screen with the
question, from <expr>, displayed in the middle and the left gadget
containing the string <pos> and, if present, the right gadget containing
the string <neg>.  If <neg> is not supplied then both gadgets will contain
the same string.  The result, 0 or 1, will be stored in the global variable
IT.  If the user clicks on the gadget with the <pos> text in it then IT
will be 1, otherwise 0.

Example:
    -- ask an important question
    answer "Do you want to quit" with !
        "Yeah, Sure", "No way"
    if it is 1
       do.menu "quit" -- aw, shucks
    else
       say "Thank you, I'll continue"
    endif

                94

Syntax:
ASK.VALUE {PROMPT <expr>}
    {INITIAL <expr>}
    {INTO var}

Function:
    This statement asks the user to input a value.  You can specify a
question, via the PROMPT clause, an initial value, via the INITIAL clause
and a destination, via the INTO clause.  If you do not specify an INTO
clause the result is put in the global variable IT>

Example:
    -- ask the user's name
    ASK.VALUE PROMPT "Enter your name" !
        INTO user.name
    SAY "THANK YOU " && USER.NAME

                95

Syntax:
AREXX  {FROM file-name}

Function:
    This statement is the way in which you start an ARexx script from
UltraCard.  If you have the script stored in an external file use the FROM
clause to specify the name of the file.  Otherwise you "collect" ARexx
scripts within a script by enclosing them in lines that start with #BEGIN
and end with #END.

                96

Example:

    SELECT.DOWN:
    -- script for a button that uses
    -- an embedded ARexx script that talks
    -- back to UltraCard and starts CygnusEd
    #BEGIN
    /* ARexx comment */
    options results

    /* Talk to UltraCard */
    address ULTRA1
    /* feed it an UltraTalk stmt            */
    /* to get the file name from UltraTalk        */
    /* global variable, file.name then        */
    /* pass to a script  loadced.rexx        */
    'get file.name'
    address rexx
    loadced.rexx result
    #END

    -- now get file name into the global
    GLOBAL file.name
    get.file.name into file.name
    if it is "NO_FILE"
        return -- user didn't select a file
    endif

    ARexx -- go start Arexx script collected
    -- above between #BEGIN and #END
    END_SELECT.DOWN

                97

Syntax:
SCREEN {TO} {FRONT/BACK}

Function:
    This statement moves the UltraCard screen in relationship to the
other draggable screens in the Amiga display.  You could use this, for
example, to run some other program and then bring the UltraCard screen back
to the front, after moving it lower on the display to act as a help screen.

Example:
    -- This script uses a public domain
    -- program that displays an IFF file and
    -- listens via an ARexx port to commands
    -- which in this case are sent by UCard
    CLI "runback show" && picture.name !
        INPUT "NIL:" OUTPUT "NIL:"
    SCREEN.MOVE 180
    -- position to bottom of display
    SCREEN TO FRONT
    -- bring our display forward
    --
    -- at this point the picture is
    -- on the screen
    -- and UltraCard is still running and can
    -- command the show program as necessary

                98

Syntax:
FIND <string> {SUPPRESS.ERROR}

Function:
    This statement searches the UltraCard stack, bringing with the
frame AFTER the current frame for the string in any data field.  If the
string is found in any data field then the global variable FIND.OBJECT is
set to the ID of the string in which the object was found.  Normally, when
used from the menu, FIND displays an error requester if the string was not
found.  You may suppress that requester using the SUPPRESS.ERROR keyword.

Example:
    -- search for a string
    ask.value "Find what value?" into it
    find it
    -- now find.object contains the id
    -- of the object in which the string
    -- was found.

                99

Syntax:
OPEN.FILE <name-expression> {OUTPUT}

Function:
    This statement opens an ASCII file for use by an UltraTalk program.
If the keyword OUTPUT is used the file is created otherwise the file is
assumed to exit.  If the open fails the global variable IT will contain the
value 0 otherwise it will contain "handle" which must be saved and used for
subsequent reading and writing.

Example:
    -- open a new text file
    GLOBAL FILE.HANDLE
    OPEN.FILE "RAM:MY.TEXT.FILE" OUTPUT
    IF it is 0
        show.msg "Couldn't open file"
        return
    ELSE
        put it into file.handle
    ENDIF

    WRITE.FILE file.handle from "Hello World"
    CLOSE.FILE file.handle

    -- open an old file
    GLOBAL FILE.HANDLE
    OPEN.FILE "RAM:MY.TEXT.FILE"
    IF it is 0
        show.msg "File not Found"
        return
    ELSE
        put it into file.handle
    ENDIF

                100

    READ.FILE file.handle into it
    SAY IT
    CLOSE.FILE file.handle

                101

Syntax:
READ.FILE <handle> {INTO <var>}

Function:
    This statement reads data from a text file previously opened via
OPEN.FILE and stores the results either into the global variable IT or a
destination of your choice if you use the INTO clause.

    It only reads one line of text at a time.  To read in multiple
lines you must use a loop.

    There is a global variable, IO.LENGTH which is set to the number of
characters actually read.  A blank line sets IO.LENGTH to 0 and end-of-file
sets IO.LENGTH to -1.

Example:
    -- assume a multi-line object named value
    OPEN.FILE "DATA.FILE"
    PUT IT INTO FILE.HANDLE

    READ.FILE FILE.HANDLE

    LOOP WHILE IO.LENGTH >= 0
        PUT IT AFTER VALUE
        READ.FILE FILE.HANDLE
    ENDLOOP

                102

Syntax:
WRITE.FILE <handle> FROM <var>

Function:
    This statement writes data from a variable or an object to a text
file previously opened via OPEN.FILE.  If the value in the variable or
object is multi-line then this writes multiple lines to the output file.

Example:
    See OPEN.FILE

                103

Syntax:
CLOSE.FILE <handle>

Function:
    This statement closes a file previously opened via OPEN.FILE.

Example:
    See OPEN.FILE

                104

Syntax:
DELETE.FILE <name>

Function:
    This statement deletes a file from the disk.  It does not ask for
confirmation so be careful what file name you pass to it!!!

Example:
    -- ask for a file and delete it
    -- this script is conservative and
    -- asks the user to confirm his choice :)
    GLOBAL file.handle
    get.file.name into fn
    if fn is "NO_FILE"
       return  -- no file was chosen
    else
        answer "Delete " && fn !
        WITH "OK", "No! Don't Do it!"
        if it is 1
        DELETE.FILE fn
       else
            show.msg "File NOT deleted"
       endif
    endif

                105

Syntax:
SORT BY <bdrop object>

Function:
    This statement rearranges the order of frames in a stack based upon
the value in a backdrop object.  Backdrop objects have their values stored
with the frame.  In this way you can have a single object with all of its
properties stored only once but a different value in each frame.  This
minimizes the amount of disk space and computing time required to use
UltraCard in data-base applications.  Therefore, this statement collects
all the strings from each frame associated with the specified object, sorts
the strings and then rearranges the order of the frames in the stack to
correspond to sorted order.

Example:
    -- from the UltraDex stack:
    SORT BY NAME

                106

Syntax:
CURSOR {WAIT | READY | HAND | LOAD <filename>}

Function:
    This function changes the shape of the mouse cursor.  The WAIT
keyword changes the mouse cursor into the Amiga ball.  In fact, multiple
uses of CURSOR WAIT will rotate the ball.  READY changes the cursor back to
the current READY cursor.  HAND changes the cursor back to the standard
UltraCard hand cursor.  The LOAD option allows you to load in an external
cursor.  The external cursor file should be 80 bytes in length and is an
extraction from the standard Intuition Preferences structure.  If you don't
know what that means don't worry most PD cursor collections will work if
the files are 80 bytes long.  NOTE: IF YOU LOAD AN EXTERNAL CURSOR THEN THE
CURSOR WILL NOT CHANGE AS YOU SWITCH FROM BROWSE TO MODIFY MODE.

Example:
    -- first, the rotating ball
    for count=1 to 10
        cursor wait
    endfor
    -- then back to the hand
    cursor hand
    -- load an external cursor
    cursor load "dh0:pointers/3darrow1.p"

                107

Syntax:
DO.MENU <menu-item-name> {SUBITEM <expr>} {NO.REQUEST}

Function:
    This statement allows you, from within a script, to select a menu
item just as if the user has chosen it with the mouse.  The
<menu-item-name> is searched for the first match scanning down the menus
fro top to bottom beginning with the leftmost menu.  The string need not be
an exact match but the first partial match that is found will be executed.
The argument to the SUBITEM clause is an integer beginning with 0 which
indicates which sub-menu item is selected.  If the keyword NO.REQUEST is
present then any confirmation request, such as that presented when you pick
the COMPACT STACK menu item will be suppressed and execution will continue
as if you had responded positively to the confirmation request.  Be
careful, if you use this with DELETE FRAME you could accidentally delete a
frame you wanted to keep so use NO.REQUEST carefully.

Example:
    -- compact a stack from within a script
    DO.MENU "COMPACT STACK" NO.REQUEST

    -- Jump to the last frame by selecting
    -- the GO/JUMP/LAST menu item
    -- from within a script
    DO.MENU "JUMP" subitem 3

                108

Syntax:
SHOW.MSG line1,line2... up to line 8 {FOR <n> SECONDS}

Function:
    This statement displays a message box of up to 8 lines of text and
an optional OK button on the screen.  You supply from 1 to 8 strings or
expressions representing the lines of text.  If you use the FOR clause then
the text will be shown for the specified number of seconds and no OK button
will be shown.

Example:
    -- simple one-line message with ok box
    -- this type of message is GREAT for
    -- debugging your scripts
    show.msg "This is a message"
    -- a complex multi-line message with ok
    show.msg "This is a multi-line", !
        "message shown using the ", !
        "SHOW.MSG", !
        "statement in UltraTalk"

    -- a message with time delay not ok box
    show.msg !
        "This message shows for 5 seconds" !
        for 5 seconds

                109

Syntax:
MOVE object BY <xdist>,<ydist>

Function:
    This statement allows you to move an object around on the UltraCard
screen.  It allows simple movement type animations.  The movement distance
is in pixels and may be positive and negative.

Example:
    -- this example moves an object 100
    -- pixels to the right, 10 pixels
    -- at a time and then moves it back
    for count=1 to 10
       move object.1 by 10,0
    endfor

    for count=1 to 10
       move object.1 by -10,0
    endfor

                110

Syntax:
FOR <var>=<start> TO <stop>
        {STEP <step>}
         -- statements
ENDFOR

Function:
    This statement simplifies the creation of loops in which the number
of iterations is known at the start of the loop.  If the step value is
positive then the <var> takes on values beginning with <start> and
INCREMENTING by <step> until it reaches or exceeds <stop>.  If the step
value is negative then the <var> takes on values beginning with <start> and
DECREMENTING by <step> until it reaches or becomes less than <stop>.  If
the STEP clause is not specified the step value is +1.

Example:
    -- count from 1 to 100
    for i=1 to 100
       say i
    endfor

    -- count down from 100 by 10's
    for i=100 to 1 step -10
       say i
    endfor

                111

Syntax:
LOOP {WHILE <expr>}
      -- statements
ENDLOOP

Function:
    This statement creates a loop that continues forever or until some
condition is met (i.e. the WHILE <expr> becomes false, that is ZERO).  If
the loop is forever you must exit with a GOTO, or a BREAK statement.

Example:
    -- a forever loop that exits with BREAK
    put 1 into count
    LOOP
        add 1 to count
        if count >= 100
            break
        endif
    ENDLOOP

    -- a loop that uses a WHILE clause
    put 1 into count
    LOOP WHILE count < 100
        add 1 to count
    ENDLOOP

                112

Syntax:
WHILE <expr>

Function:
    This statement is used in conjunction with the LOOP statement to
create loops with a text at the bottom.  When the <expr> becomes FALSE
(i.e. ZERO) then the loop is exited.

Example:
    -- loop with WHILE statement
    put 1 into count
    LOOP
        add 1 to count
    WHILE count < 100
    ENDLOOP

                113

Syntax:
BREAK

Function:
    This statement is used with LOOP and FOR constructs.  When it is
encountered it causes control to pass to the first statement after the end
of the ENDLOOP or ENDFOR.

Example:
    -- loop exit using BREAK
    put 1 into count
    LOOP
        add 1 to count
        if count >= 100
            break
        endif
    ENDLOOP

    -- for exit using break
    FOR i=1 to 100
        if i = 55
            break
        endif
    ENDFOR

                114

Syntax:
CONTINUE

Function:
    This statement is used with LOOP and FOR constructs.  When it is
encountered it causes control to pass to the beginning of the loop and the
remainder of statements in the loop are skipped.

Example:
    -- SAY only even numbers
    for i=1 to 100
        if i % 2 = 0
            continue -- bypass rest of loop
            endif
        say i
    endfor

                115

                   ULTRATALK BUILT-IN FUNCTIONS

You may use a built-in function any place that a variable may be used
EXCEPT as a destination (such as PUT...INTO destination)

Function:    ABS(expr)

Returns:
    The absolute value of a numeric expression

Example:
    ABS(-3) -- returns 3

                116

Function:    CHAR.TO.NUM(expr)

Returns:
    The numeric value of the first character of the expression.

Example:
    CHAR.TO.NUM("A") returns 65

                117

Function:    LEFT(expr,numchars)

Returns:
    The left-most <numchars> characters of the expression.

Example:
    LEFT("ABCDEFGHIJLKMN",5)
    -- returns "ABCDE"

                118

Function:    LENGTH(expr)

Returns:
    The length of the string value of the expression.

Example:
    LENGTH("ABCDEFGHI") returns 9

                119

Function:    NUM.TO.CHAR(expr)

Returns:
    The string value, a single character string, of the ascii
equivalent of the expression.

Example:
    NUM.TO.CHAR(66) returns "B"

                120

Function:    PARM(expr)

Returns:
    The value of a parameter to a user written function.  If you use a
name, followed by expressions in parenthesis, UltraTalk thinks you are
calling a "function".  It evaluates the arguments and then sends a symbolic
message using the name of the function.  When you write the handler you use
the PARM function to retrieve the arguments from the caller's parameter
list.

Example:
    MY_FUNC:
       say "The first parameter is " !
        && PARM(1)
       say "The second parameter is " !
        && PARM(2)
       Put Parm(1) after Parm(2)

                121

       Return Parm(2)
    END_MYFUNC

    Select:
        PUT "ABCD" into var1
        PUT "EFGH" into var2
        say MY_FUNC(var1,var2)
        -- will say "ABCDEFGH"
    END_SELECT

                122

Function:    PARM.COUNT

Result:
    The number of parameters that have been passed to a user written
function.  There is a maximum number of 10 parameters.  This function will
return the number of parameters actually passed.  It is useful to check to
see if the number of parameters is correct.

Example:
    MY_FUNC:

    -- check to make sure argument list was
    -- right, i.e. user passed to parms

    IF Parm.Count <> 2
        Return "ERROR"

                123

    ENDIF

      say "The first parameter is " !
        && PARM(1)
      say "The second parameter is " !
        && PARM(2)
      Put Parm(1) after Parm(2)
      Return Parm(2)
    END_MYFUNC

                124

Function:    RIGHT(expr,num)

Returns:
    The rightmost <num> characters of the string expression.

Example:
    RIGHT ("ABCDEF",3) returns "DEF"

                125

Function:    DATE

Returns:
    The date, as a string.

Example:
    PUT DATE into todays.date

                126

Function:    DAY

Returns:
    The day of the week, as a 3 character abbrev.

Example:
    DAY returns "SUN"

                127

Function:    DAY.OF.THE.WEEK

Returns:
    A number corresponding to the day of the week where 1 = SUNDAY, 2 =
MONDAY and so on until 7 = SATURDAY

Example:
    DAY.OF.THE.WEEK returns 1 on the Sunday

                128

Function:    MONTH

Returns:
    A string containing the 3 character abbrev. for the current month.

Example:
    MONTH returns "Jan" during June

                129

Function:    YEAR

Returns:
    A string containing the last two digits of the current year.

Example:
    YEAR returns "89" for the year 1989

                130

Function:    TIME

Returns:
    A string containing the hours, minutes, seconds and AM/PM for the
current time.

Example:
    TIME returns "10:00:05 AM" for 5 seconds after 10:00 AM.

                131

Function:    WORD(index,expr)

Returns:
    A string containing the "index-th" word in the expression.  Word
numbering begins at 1.

Example:
    WORD(2, "This is a test") -- returns "is"

                132

Function:    LINE(index,expr)

Returns:
    A string representing the "index-th" line in the expression.  Most
useful for multi-line values.  Line numbering begins at 1.

Example:

    Assume we have a multi-line object containing:

    +------------------------+
    | UltraCard              |
    | Hypermedia Software    |
    | From                   |
    | Intuitive Technologies |
    +------------------------+

Line(2,field) would return:
"Hypermedia Software"

                133

Function:    ITEM(index,expr)

Returns:
    The index-th "item" from the expression.  Items are separated by
commas.

Example:
    Item(3, "ABC,DEF,GHI,JKL")
    -- returns "GHI"

                134

Function:    OBJECT(expr)

Returns:
    The name of the object whose id number is contained in expr.
Useful with the GET statement to select objects other than by name.

Example:
    GET the Top.Line of Object(3)

                135

Function:    STILLDOWN

Return:
    TRUE if the mouse button is still down.  This is used in the
SELECT.DOWN handler to track the mouse.

                136

Function:    VERSION

Returns:
    The version number of UltraCard as a string.  it is in the form:

    MMmmxxxx

where MM is the major version (like 01) and mm is the minor version (like
30) and xxxx is reserved.

The VERSION function returns the word "VERSION" on releases prior to 1.2.1.
In version 1.3 it returns "01300000".

                137

Function:    BDROP.ID

Returns:
    The id number of the current backdrop.  Using this function you can
write scripts that step through a stack and know when the backdrop changes
by monitoring the value of BDROP.ID.

                138

Function:     AVAILABLE.MEMORY

Returns:
    The amount of TOTAL available memory.  It includes both CHIP and
FAST memory.

                139

Function:    AVAILABLE.CHIP.MEMORY

This function returns the amount of CHIP memory available.  You could use
the value of this function to determine whether or not you need to use the
SLEEP statement when preparing to run another program:

    If Available.Chip.Memory < 128000
        SLEEP
    Endif
    WORKBENCH "dh0:planit"
    WakeUp
    -- doesn't hurt if you weren't sleeping!

                140

Function:    NEXT.FRAME.OBJECT(parm)

This function allows you to step through the objects of a frame and examine
their contents and/or properties.  The first call the NEXT.FRAME.OBJECT
should be made with a parm of 0.  The function returns the OBJECT id of the
next object in the frame.  You can then use this id number with the
OBJECT() function to find information about the object.  The second through
last calls to NEXT.FRAME.OBJECT should pass the result of the previous
call.  NEXT.FRAME.OBJECT returns -1 when you have reached the end of the
list.

Example:
    Say the location of each object in the frame.

put 0 into id
LOOP

                141

   put.next.frame.object(id) into id

   if id is -1
    -- check for last obj in frame
    break
   endif

   get top.edge of object(id) into top.pos
   get left.edge of object(id) into left.pos
   say "object " && id && " is at " && !
     left.pos && "  " && top.pos
ENDLOOP

                142

Function:    NEXT.BACKDROP.OBJECT

This works identically to the NEXT.FRAME.OBJECT function described above
except that it steps through the objects in the current backdrop.

                143

                   ULTRATALK GLOBAL VARIABLES

    Within the UltraCard program there are a number of predefined
global variables.  Some of these control aspects of the program's behavior
and some are set by the program for use by your scripts.

    This is a complete description of all the built-in globals and what
they mean.

LAST.DATE

set by the DATE function to the number of days since January 1, 1978.  It
is then subsequently used in all the calculations of Day.Of.The.Week, etc.
It is a global variable so that you can calculate a different value and use
the built-in functions to extract information from that value (such as the
Month, Day.Of.The.Week, etc.)

CHAT

set by typing into the chat window.  If the chat window is on the screen
you can "put" an expression into the variable CHAT and it will appear in
the window immediately.

IT

the most default repository of information in UltraTalk.  Most statements
store information here if no other destination is given.

                144

WIDTH.ADJUST

this is a numeric value which is used when performing graphic printing.  It
is defaulted to print 640 wide images as a full page wide and 320 wide
images as a 1/2 page wide.  Change it before you select either Print/Screen
or Print/Stack.

HEIGHT.ADJUST

this is a numeric value which is used when performing graphic printing.  It
is defaulted to print 200 high images as 1/3 page height and 400 high
images as 2/3 page height.  Change it before you select either Print/Screen
or Print/Stack.

CANT.MODIFY

this is a boolean value.  If it is non-zero then you are not allowed to
enter MODIFY mode via the menu item or the F2 function key.

CANT.ADD.FRAME

this is a boolean value.  If it is non-zero then you are not allowed to add
frames to the current stack either with or without new backdrop and you
also are prohibited from duplicating a frame.

CANT.DELETE.FRAME

this is a boolean value.  If it is non-zero then you are now allowed to
delete a frame.

                145

SAVE.GLOBALS

this is a boolean value.  It defaults to FALSE.  If you set this to true in
a script then a copy of the global variables will be stored in the
currently open stack when it is closed either by opening another stack or
quitting the program.  Normally global variable changes are not permanently
recorded.

IN.MODIFY

this is a boolean value.  If it is non-zero then the program is currently
in MODIFY mode.  You can test this value in your scripts to determine, for
example, if your function key handler should perform a browse function or a
modify function.

FADE

this is a boolean value.  If it is non-zero then the screen fades to black
and back again on each JUMP.  This is particularly effective if the frame
to which you are jumping is in a different color palette.

DATA.CURSOR

this is a color value.  Normally the vertical line cursor used for
single-line data entry is shown as color 1.  By putting a different value
into DATA.CURSOR you can customize this.

TRUE

                146

this is a constant.  Its value is "1"

FALSE

this is a constant.  Its value is "0"

MOUSE.X

this is the mouse horizontal position, in pixels, when the current message
was originally sent.

MOUSE.Y

this is the mouse vertical position, in pixels, when the current message
was originally sent.

SHIFT.KEY

this is a boolean.  If either shift key was down when the last system
message was received then this is TRUE.

ALT.KEY

this is a boolean.  If either alt key was down when the last system message
was received then this is TRUE.

CONTROL.KEY

this is a boolean.  If the control key was down when the last system
message was received then this is TRUE.

                147

EXTERNAL.SCRIPTER

this is a program name.  It contains the name of the program to run when
the ARexx statement is executed.  By default this is "C:RUN C:RX" to run
ARexx scripts.

EDITOR

this is a program name.  It contains the name of the program to run when
the External Editor menu item is selected in the UltraTalk editor.

PAINT

this is a program name.  It contains the name of the program to run when
the IFF/Paint menu item is selected in MODIFY mode.  It is normally run
using a Workbench interface (because DPAINT requires it) but if the paint
program you are using can accept CLI type arguments then put and asterisk
(*) as the first character of this string and the program will be invoked
using a CLI interface instead of a Workbench one.

                148

VISUAL.EFFECT

this is a number that represents which visual effect is to be used when a
JUMP WITH EFFECT is executed.

    The following are the allowed values of the global variable
VISUAL.EFFECT (and their meanings):

    0    -    Same as effect 1
    1    -    CUT - full screen single blit
    2    -    Wipe Down
    3    -    Wipe Up
    4    -    Wipe Left to Right
    5    -    Wipe Right to Left
    6    -    Curtain Open
    7    -    Curtain Close
    8    -    Slide on Left to Right
    9    -    Slide on Right to Left
       10    -    Slide Top to Bottom
       11    -    Slide Bottom to Top
       12    -    Zoom out from center
       13    -    Zoom in from outer edges
       14    -    Zoom out from point in EFFECT.X, EFFECT.Y
       15    -    Zoom in from point in EFFECT.X, EFFECT.Y

                149

EFFECT.SPEED

this is a number ranging from 1 to 10 indicating how fast the visual effect
should be performed.  Since this interacts with EFFECT.AMOUNT (see below)
you can vary the apparent speed by using slower speeds and larger amounts
or by using faster speeds and smaller amounts.

EFFECT.AMOUNT

this is a number that varies depending upon the visual effect involved.  It
is the number of pixels that are transferred at one time from the new image
to the screen.  For example, if you are using effect 5 (wipe right to left)
an amount of 64 for a 640 wide screen will accomplish the effect in 640
steps.  This value is forced to be an even multiple of the screen size,
depending upon the effect.

EFFECT.X

this is a number used for effects 14 and 15 to indicate a point on the
screen where the zoom should focus.

EFFECT.Y

this is a number used for effects 14 and 15 to indicate a point on the
screen where the zoom should focus.

                150

NEXT.FILE.NAME

this is a string.  It is NOT empty then the next time the file selector
would appear on the screen the value of this variable is returned instead.
In this way you can, in combination with DO.MENU, operate the menus that
ask for filenames under script control.  After each file select which
accesses NEXT.FILE.NAME this variable is set to the empty string.

MULTI.MOUSE.MOVE

this is a boolean.  If it is still non-zero then while in a loop monitoring
the STILL.DOWN function mouse movements are compressed.  This gives faster
response.  Compression means that all mouse movement messages that are
queued by Intuition between calls to the STILL.DOWN function are reduced to
a single movement calculation.

DOWN.SOUND

this is a file name string.  If it is non-empty then this file is assumed
to contain a digitized sound and it is played when any button is clicked.
Normally you would copy the sound file to a ram based disk (such as RAM: or
RAD:) and put that name into DOWN.SOUND

                151

UP.SOUND

this is a file string.  If it is non-empty then this file is assumed to
contain a digitized sound and it is played when any button is released.
Normally you would copy the sound file to a ram based disk (such as RAM: or
RAD:) and put that name into UP.SOUND.

GRID.AMOUNT

this is a number.  While in MODIFY mode positioning of objects is limited
to specific boundaries based upon the value of GRID.AMOUNT.  If this
variable contains, for example, 4 then objects can only be moved to pixel
locations evenly divisible by 4. This can be quite handy when creating
tables, etc.  Normally you simply use the chat window to execute the
statement:

    put 4 into grid.amount

or whatever value you want for grid resolution.

ME

this is a number.  It contains the ID of the object in which the current
script is executing.  You can use this as an argument to the OBJECT()
function.  You should use ME as opposed to direct object id's or names when
coding scripts that refer to the object itself so that your scripts can be
copied and put into new objects you create and no changes will be required.

                152

TARGET

this is a number.  It contains the ID of the object which first processed
the message. It can be useful when used in conjunction with PASS.

THE.KEY

this is an ASCII character as a 1 character string.  it is used in
conjunction with the KEY.PRESS message and contains the most recent key
that was pressed.

RAW.KEY

this is a number.  It contains the raw key code for the most recent key
that was pressed.  It is used in conjunction with the KEY.PRESS message.

TAB.KEY.OBJECT

this is the ID of the object in which the TAB or RETURN key was most
recently pressed.  By using this you can determine, as is done in the STACK
script of the UltraDex stack, which object to activate next.

SELECTION

this is the ID of the selected object when in MODIFY mode.  By using this
and the OBJECT() function you can make property changes to the currently
selected object.

                153

FIND.OBJECT

this is the ID of the object in which the string was found during the FIND
statement.

IO.LENGTH

this is a number indicating how many characters were read during the last
READ.FILE statement.  It is 0 for a blank line and -1 for end-of-file.

PATHWAYS

this is a multi-line text value containing the names of directories to
search when a JUMP statement specifies a stack name that is not fully
qualified (e.g. JUMP HELP).  It defaults to:

    ULTRA:
    ULTRA:STACKS
    ULTRA2:STACKS

SERIAL.PREFIX

this is a string that, if not empty, is sent before the user specified
characters during a SERIAL.WRITE statement.

SERIAL.SUFFIX

this is a string that, if not empty, is sent after the user specified
characters during a SERIAL.WRITE statement.

                154

SERIAL.ERROR

this is a string that contains either 0 or "TIMEOUT" and is referenced
after a SERIAL.READ statement.

The following are constants you can use to make your scripts more readable:

ONE
TWO
THREE
FOUR
FIVE
SIX
SEVEN
EIGHT
NINE
TEN

                155

                     UltraCard Object Properties

    Listed below are the properties of an UltraCard object that can be
retrieved and stored using the GET and SET UltraCard statements.

HiliteMode
    0 - None
    1 - Invert
    2 - Outline

NameDisplay
    0 - ShowLeft
    1 - ShowTop
    2 - ShowRight
    3 - ShowBottom
    4 - ShowInside
    5 - Hidden

Name
    Character String

NameFont
    Character String, font name followed by size, e.g.
TOPAZ 8 or RUBY 15

NameColor
    Number, 0 to max-1

                156

NameStyle
    Bit encoded, OR together for multiple styles

    0 - Normal
    1 - Bold
    2 - Italic
    4 - Underline

Render
    0 - Clear
    1 - Solid

FillColor
    0 through 63 means solid color fill

    (Note: The following three values may be retrieved but DO NOT set
    them because there are other data items which must accompany them,
    like a bitmap, which unless the property is set by the program via
    the menu, it will NOT work!)

    43690 - Object is GRAPHIC fill
    56797 - Object is Horizontal Slider fill
    61166 - Object is Vertical Slider fill

                157

OutlineStyle
    0 - None
    1 - Single
    2 - Double
    3 - Triple

OutlineColor
    0 to 63

Shape
    0 - Circle/Ellipse
    1 - Box
    2 - Horizontal Line
    3 - Vertical Line
    4 - Diagonal Line 1
    5 - Diagonal Line 2

DropShadow
    0 - None
    1 - Light
    2 - Medium
    3 - Heavy

ShadowColor
    0 to 63

Visible
    0 - Hidden
    1 - Visible

                158

ScrollBar
    0 - Hidden
    1 - Visible

ScrollBarColor
    0 to 63

ScrollBarOrientation
    0 - Horizontal
    1 - Vertical

Hypertext
    A string value

NameShadow
    0 - No
    1 - Yes

NameShadowColor
    0 to 63

ValueColor
    0 to 63

ValueVisible
    0 - No
    1 - Yes

ValueLock
    0 - Editable
    1 - Locked

                159

ValueShadow
    0 - No
    1 - Yes

ValueShadowColor
    0 to 63

ValueStyle
    Bit encoded, OR together for multiple styles.

    0 - Normal
    1 - Bold
    2 - Italic
    4 - Underline

MultiLine
    0 - Single Line
    1 - Multiple Line Value Display

TopLine
    Numeric value, beginning with 0, indicating which line of a
multi-line value is displayed at the top of the value display area.

LeftEdge
    Numeric value, screen position

TopEdge
    Numeric value, screen position

Width
    Numeric value, screen position

                160

Height
    Numeric value, screen position

ValueLineCount
    Numeric value, number of lines in a multi-line value (after word
wrap) or the maximum value for a slider fill.

Script
    Character string of the object's script.  If you set an object
script using this the next script will not take effect immediately.

                161

                        UltraCard Messages

    This section lists all of the messages that are generated by
UltraCard and what they mean.

Entry/Exit Messages

    These messages are generated whenever an environment is entered or
exited.  There are empty handlers already supplied for you at each of these
levels.  If you need to do anything, such as declare global variables or
initialize objects, etc. you should put that code in the entry and exit
handlers for the appropriate level.

Stack.Entry    - when stack is opened
Stack.Exit    - at very end when stack is closed
BackDrop.Entry  - when backdrop is opened
BackDrop.Exit    - when backdrop is closed
Frame.Entry    - when frame is opened
Frame.Exit    - when frame is closed

Object Messages

    The following messages are generated by a mouse click inside an
object.  If you do not supply ARROW1 and ARROW2 handlers the built-in
handlers (that scroll at machine code speed) are used.

SELECT.DOWN    - when mouse is clicked in object
SELECT.UP    - when mouse is released in object
 ARROW1        - when up/left arrow is clicked
 ARROW2        - when down/right arrow is clicked

                162

Mouse Messages

    The following messages are generated by a mouse click outside an
object.

CLICK.DOWN    - when mouse is clicked down but not in an object
CLICK.UP    - when mouse is released but not in an object

Timer Messages

    These messages are sent as the UltraCard program timer expires and
counts the various time amounts.  If there are no handlers for these
messages they are ignored.

QUARTER.SECOND.TICK    - every 1/4 second
SECOND.TICK        - every 1 second
MINUTE.TICK        - every 60 seconds
HOUR.TICK        - every 3600 seconds
DAY.TICK        - every 24 hours

Intercept Messages

    The following messages are sent when a menu item is selected that
means the user wants to run a specialized external program, paint or edit.
The data that the program is to operate on is already prepared.  There are
default handlers built-in to the program that

                163

start the programs configured by the preferences frame in the ControlRoom
stack.  However, as in the case of DigiPaint, some paint programs cannot
import/export non-HAM images.  So by coding a handler for these messages
you can preprocess or postprocess the data sent to and from the external
program.

RUN.EDIT    - when the External Editor menu item is chosen in the
          UltraTalk editor.  The data is already written to the
          file:  "T:ULTRA.EDIT".

RUN.PAINT    - the IFF/Paint menu item is chosen in MODIFY mode.  The
          backdrop is already written to the file: "T:ULTRAPIC".

Misc.

PRINT.REPORT    - this is always generated by the user choosing the
          Print/Report menu item because that is all the menu item
          does.  You should code a handler for this message at the
          stack script level to do a custom report.

Keyboard Messages

KEY.PRESS    - when any key is pressed that is not a special key.
           Special keys generate their own messages (see below).
          The ASCII character is in the global variable THE.KEY
          and the raw key code value is in RAW.KEY, as a number.

ESCAPE

UP.ARROW    )
DOWN.ARROW    ) KEYBOARD ARROW KEYS
RIGHT.ARROW    )
LEFT.ARROW    )

KEY.F1
KEY.F2
KEY.F3
KEY.F4
KEY.F5
KEY.F6
KEY.F7
KEY.F8
KEY.F9
KEY.F10
KEY.HELP

TAB.KEY        - only generated when data entry is operating, otherwise
          the tab key generates a regular KEY.PRESS message.

RETURN.KEY    - like tab key, only generated when RETURN key is pressed
          during data entry.

                165

                        Creating A New Stack

    To create your own stacks you should take the following steps:

1.  Select New Stack from the Project menu.

2.  Select the resolution and number of colors from the requester that
    appears.

3.  Wait for the requester that tells you that your stack is ready to go.

4.  Click OK.

5.  To begin adding objects and pictures to your stack you must enter
    Modify mode.  Pick Modify... from the Edit menu or press F2.

6.  The most often thing that is done first is to import an IFF picture as
    a backdrop.  If you choose a picture that is the wrong resolution or
    depth, UltraCard will beep and then tell you what resolution you must
    use to import the picture.

7.  To create object, pick from the New item under the Edit menu.  Note
    that they have keyboard shortcuts based upon the Esc key.

8.  To add additional frames using the same backdrop picture and fields you
    must return to Browse mode (Press F1) and select Add

                166

   from the Frame item under the Edit menu.

9.  To add additional frames with a new backdrop picture and fields you
    must return to Browse mode and select Add New BD from the Frame item
    under the Edit menu.

10. Use the items under the Info menu to help you keep track of your
    backdrops and frames.

                167

                      UltraCard Menu Reference

                         Browse Mode Menus

PROJECT

    NEW STACK
        Allows you to create a new stack.  You will be prompted
        for a name.  A requester will pop up asking for resolution
        and colors.

    OPEN STACK
        Allows you to open an existing stack.  You will be prompted
        for a name using the UltraCard standard file selector.

    COMPACT STACK
        Your stack will have the "empty" space squeezed out of it.
        As you use stacks they "grow".  Your old stack will be
        renamed with ".OLD' at the end of its name and a new stack
        will be created that contains all your information but
        taking less space on the disk and operating faster.

    PROTECT STACK
        You will be prompted for a password.  From then on you must
        supply the password when you open the stack.

                168

    OUTPUT TO
        Allows you to select whether print screen is to the
        printer or to a file.

        FILE

        PRINTER

    PRINT
        Allows you to pick a single frame, a whole stack or to
        send a message to your scripts to print a report.  Refer
        to the GLOBAL variables section for the use of the
        HEIGHT.ADJUST and WIDTH.ADJUST variables and how they
        affect printing SCREEN and STACK.  The Report sub-item
        simply sends the message PRINT.REPORT for which you must
        write a handler.

        SCREEN

        STACK

        REPORT

    OPEN WORKBENCH
        Allows you to open the workbench screen if you closed it
        to save memory.

                169

    CLOSE WORKBENCH
        Allows you to close the workbench screen to save CHIP
        memory.  If you have ANY open windows other than workbench
        windows, such as a CLI window or a clock then the
        workbench will not close.

    ABOUT ULTRACARD
        Tells you the version number of your copy of UltraCard.

    ICONIFY
        Shrinks the program down to an icon on the workbench
        screen and releases all the CHIP memory used for the
        screen.  Handy when you are using a paint program in a
        512K Agnus machine.

    QUIT
        Leaves UltraCard.

EDIT

    FRAME
        Allows you to add, delete and duplicate frames.

        ADD
            Adds new frame using the current backdrop.

        ADD NEW BD
            Adds new frame and creates a new, empty (blank)
            backdrop.

                170

        DELETE
            Deletes the currently visible frame.  Asks for
            confirmation.

        DUPLICATE
            Make a duplicate of the currently visible frame.
            After this menu selection you are positioned on the
            NEW frame.

    INFO
        Gives information about the item selected.

        STACK

        BACKDROP

        FRAME

    MODIFY...
        Allows you to enter modify mode.  You may also press F2.

GO

    HELP
        Pushes the location of the currently visible frame and
        jumps to the Help stack.

    BACK
        Navigates back to the last visible frame.  Could be in
        another stack.

                171

    JUMP
        Allows navigation within the current stack.

        FIRST

        NEXT

        PREV

        LAST

    RECENT
        Shows the list of the previous 25 unique frames you have
        visited.  You may choose from the list for a direct jump.

    FIND
        Allows you to find a string in the value portion of any
        object.

    CHAT
        Opens the CHAT window that allows you to type a single
        UltraTalk command.

                172

                         Modify Mode Menus

EDIT

    NEW OBJECT
        Allows you to create a new object in the layer specified.

        FRAME (shortcut Esc)

        BACKDROP (shortcut Shift/Esc)

    CUT
        Copies selected object to clipboard and removes object
        from screen.

    COPY
        Copies selected object to clipboard.

    PASTE
        Copies clipboard to screen.

    CLEAR
        Removes selected object, no UNDO!

    UNDO
        Restores object location/size after a move or sizing
        operation.

                173

    SCRIPT
        Allows you to edit the selected script.

        STACK

        BACKDROP

        FRAME

    IFF
        Allows you to import and export the screen from/to IFF
        files.  If you hold down the SHIFT key when selecting
        EXPORT or PAINT it will include the objects in the IFF
        file.  If you don't hold down the shift key only the
        backdrop picture will be included.

        IMPORT

        EXPORT

        PAINT
            Exports current backdrop to an IFF file and runs
            the program specified in the global variable
            "PAINT".  See the message section about RUN.PAINT.

    COPY FRAME
        Copies the current frame to a special "frame clipboard".
        Note: This does not copy the backdrop picture or the
        backdrop objects!

                174

    PASTE FRAME
        Copy the contents of the "frame clipboard" into the
        current frame.  Replaces all frame objects.

    OBJECT IN
        Allows you to tell what layer the currently selected
        object resides in.

        BDROP

        FRAME

    SELECT BY NAME
        Allows you to select an object by name even if the object
        is not visible or is off screen.

        BDROP

        FRAME

    BROWSE
        Allows you to return to BROWSE mode.  You can also press
        F1.

PROPERTIES

    SCRIPT
        Allows you to edit the script of the selected object.

    INFO
        Shows information about the selected object, color, style,
        location, etc.

                175

    HILITE
        Allows you to choose how the visible feedback is shown
        when the user clicks on your object.

        NONE

        INVERT

        OUTLINE

    NAME
        Allows you to alter how, where, and in what font/color
        the object name is shown.

        SHOW AT LEFT

        SHOW AT TOP

        SHOW AT BOTTOM

        SHOW INSIDE

        HIDE

        CHANGE...

        FONT

        COLOR

    NAME STYLE
        Allows you to make your name show in a type style.

        PLAIN

                176

        BOLD

        ITALIC

        UNDERLINE

        DROP SHADOW

        SHADOW COLOR

    RENDER
        Allows you to have your objects transparent or solid.

        A transparent graphic object is graphically and LOGICALLY
        transparent wherever it contains pixels of color 0.  This
        means that you can create irregularly shaped objects and
        layer them.

        CLEAR

        SOLID

    FILL
        Objects can be filled with solid colors, graphic bits,
        proportional sliders, or in UltraCard Plus an external fill
        such as an animation.

        COLOR

        GRAPHIC
            Choosing this not only selects the graphic fill
            property but also allows you to extract the
            graphic image from an IFF picture.  When you have

                177

            the picture and the cursor changes to the
            cross-hairs click and drag a box around the area
            you wish to use as a graphic fill.  When you
            release the mouse button the picture will disappear
            and the stack backdrop will reappear with the
            object filled in as selected.

        HORIZ. SLIDER

        VERT. SLIDER

        EXTERNAL

        COLOR...

    DROP SHADOW
        Allows you to choose a drop shadow effect for your objects
        to give them the appearance of depth.

        NONE

        LIGHT

        MEDIUM

        HEAVY

        COLOR...

    OUTLINE
        Allows you to choose outline display for your objects to
        enhance their appearance.

        NONE

                178

        SINGLE

        DOUBLE

        TRIPLE

        COLOR

    SHAPE
        Allows you to choose the shape of the fill for your object.

        CIRCLE/ELLIPSE

        BOX

        HORIZ. LINE

        VERT. LINE

        DIAG. LINE 1

        DIAG. LINE 2

    VISIBLE
        Objects can be visible or hidden and then made visible by
        script control.

        YES

        NO

    SET CUSTOM
        These menu items generate messages SET.CUSTOM1 through
        SET.CUSTOM4 for which you can write handlers in your stack
        script to set multiple property

                179

        adjustments.  If you do not write special handlers they
        have no effect.

        1
        2
        3
        4

                180

CONTENTS

    VALUE
        Every object can have a value.  This menu's items allow
        you to choose if that value is to be shown, is editable
        by the user and in what color it appears.

        HIDE

        SHOW

        EDIT

        LOCK

        COLOR

    VALUE STYLE
        Allows you to enhance the display of your objects value.

        PLAIN

        BOLD

        ITALIC

        UNDERLINE

        DROP SHADOW

        SHADOW COLOR

                181

        MULTILINE
            If YES is chosen here then the value is
            word-wrapped to fit and can be scrolled.

            YES

            NO

        HYPERTEXT...
            Allows you to manipulate the HYPERTEXT property of
            your object.  This is applicable only to multi-line
            objects.  See the MANUAL stack for more details.

        SCROLLER
            Allows you to enable or disable scrolling arrows
            for multi-line objects.

            HIDE

            SHOW

            HORIZONTAL

            VERTICAL

            COLOR...

                182

                               Index

Arrow Key
    Down 20
    Up 20
BBS
    Phone Number 22
Browser
    Distribution of 23
Expressions
    Operators 35
Objects
    Building Blocks 17
    Types Of 17
Pathways
    Setting 14
Stacks
    ControlRoom 12
    Loading Others 14
    Manual 15
UltraCard
    Features 5
    What can it do? 2
    What is it? 1
    When to use 4
UltraTalk
    Data Values 25
    Expressions 35
    Function Handlers 34
    Functions 116
        ABS 116
        AVAILABLE.CHIP.MEMORY 139
        AVAILABLE.MEMORY 138
        BDROP.ID 137

                183

        CHAR.TO.NUM 117
        DATE 125
        DAY 126
        DAY.OF.THE.WEEK 127
        ITEM 133
        LEFT 118
        LENGTH 119
        LINE 132
        MONTH 128
        NEXT.BACKDROP.OBJECT 142
        NEXT.FRAME.OBJECT 140
        NUM.TO.CHAR 120
        OBJECT 134
        PARM 121
        PARMCOUNT 123
        RIGHT 124
        STILLDOWN 135
        TIME 130
        VERSION 136
        WORD 131
        YEAR 129
    Global Variables 144
    Message Handlers 31
    Message Hierarchy 29
    Message Transformation 30
    Messages 29, 162
    Properties 156
    Statement Handlers 33
    Statements
        ADD 72
        ANSWER 94
        AREXX 96
        ASK.VALUE 95
        BREAK 114
        CHANGE 55
        CHOOSE 56
        CLEAR 90
        CLI 63
        CLOSE.FILE 104

                184

        CONTINUE 115
        COPY 88
        CURSOR 107
        CUT 87
        CYCLE.COLOR 41
        DELAY 93
        DELETE.FILE 105
        DIVIDE 75
        DO.MENU 108
        ELSE 67
        ENDFOR 111
        ENDIF 67
        ENDLOOP 112
        ENTER.MODIFY 84
        EXIT.MODIFY 85
        FIND 99
        FOR 111
        GET 76
        GET.FILE.NAME 66
        GLOBAL 71
        GOTO 70
        GRAPHIC.FILL 45
        IF 67
        JUMP 39
        LOAD.SOUND 57
        LOCK.SCREEN 77
        LOOP 112
        MENUS 47
        MOVE 110
        MOVE.SCREEN 53
        MULTIPLY 74
        NEW.OBJECT 86
        OPEN.FILE 100
        PASS 79
        PASTE 89
        PLAY 61
        POP 80
        PUSH 81
        PUT 40
        READ.FILE 102

                185

        RETURN 82
        SAVE.BRUSH 44
        SAY 38
        SCREEN 98
        SCREEN.TITLE 54
        SELECT.OBJECT 92
        SEND 83
        SERIAL.CLOSE 49
        SERIAL.FLUSH 52
        SERIAL.OPEN 48
        SERIAL.READ 50
        SERIAL.WRITE 51
        SET 68
        SET.COLOR 91
        SET.SCRIPT 46
        SHOW.MSG 109
        SLEEP 42
        SORT 106
        STOP.SOUND 60
        SUBTRACT 73
        UNLOAD.SOUND 58
        UNLOCK.SCREEN 78
        WAIT 65
        WAIT.SOUND 58
        WAKE.UP 43
        WHILE 113
        WORKBENCH 64
        WRITE.FILE 103
    Syntax 24
    Syntax Description 37
    Variables
        Global 32
        Local 32

                186

============================================================================
         DOCS PROVIDED BY  -+*+-THE SOUTHERN STAR-+*+- for M.A.A.D.
============================================================================